<p>The DateTime object is defined in PHP versions 5.2 and greater.  Full documentation can be found at <a href="http://php.net/datetime">php.net/datetime</a>.</p>

<p>PHP's <strong>print_r()</strong>, <a href="http://drupal.org/project/devel">Devel module</a>'s <strong>dpm()</strong>, and similar functions and most debuggers are not able to show the properties of DateTime objects.  The <strong>date_format()</strong> function provides a good alternate method to debug DateTime objects.  An example of its usage follows, including some common DateTime manipulation functions;</p>

<p>
  <!-- PHP colorized by input filter on Drupal.org, from http://drupal.org/node/337764#comment-1132868 -->
  <span style="color: rgb(0, 0, 0);"><span style="color: rgb(0, 0, 187);">&lt;?php<br /></span><span style="color: rgb(255, 128, 0);">// Create a DateTime object for 11 November 2008, 5pm, Chicago time.<br /></span><span style="color: rgb(0, 0, 187);">$date</span> <span style="color: rgb(0, 119, 0);">=</span> <span style="color: rgb(0, 0, 187);">date_create</span><span style="color: rgb(0, 119, 0);">(</span><span style="color: rgb(221, 0, 0);">'2008-11-11 17:00:00'</span><span style="color: rgb(0, 119, 0);">,</span> <span style="color: rgb(0, 0, 187);">timezone_open</span><span style="color: rgb(0, 119, 0);">(</span><span style="color: rgb(221, 0, 0);">'America/Chicago'</span><span style="color: rgb(0, 119, 0);">));<br />
  <br /></span><span style="color: rgb(255, 128, 0);">// Find out what time it is in New York.<br /></span><span style="color: rgb(0, 0, 187);">date_timezone_set</span><span style="color: rgb(0, 119, 0);">(</span><span style="color: rgb(0, 0, 187);">$date</span><span style="color: rgb(0, 119, 0);">,</span> <span style="color: rgb(0, 0, 187);">timezone_open</span><span style="color: rgb(0, 119, 0);">(</span><span style="color: rgb(221, 0, 0);">'America/New_York'</span><span style="color: rgb(0, 119, 0);">));<br />
  <br /></span><span style="color: rgb(255, 128, 0);">// Now move it ahead to the following Tuesday.<br /></span><span style="color: rgb(0, 0, 187);">date_modify</span><span style="color: rgb(0, 119, 0);">(</span><span style="color: rgb(0, 0, 187);">$date</span><span style="color: rgb(0, 119, 0);">,</span> <span style="color: rgb(221, 0, 0);">'+1 Tuesday'</span><span style="color: rgb(0, 119, 0);">);<br />
  <br /></span><span style="color: rgb(255, 128, 0);">// Print out the result.<br /></span><span style="color: rgb(0, 119, 0);">print</span> <span style="color: rgb(0, 0, 187);">date_format</span><span style="color: rgb(0, 119, 0);">(</span><span style="color: rgb(0, 0, 187);">$date</span><span style="color: rgb(0, 119, 0);">,</span> <span style="color: rgb(221, 0, 0);">'l r'</span><span style="color: rgb(0, 119, 0);">);
  <br /></span><span style="color: rgb(255, 128, 0);">// "Tuesday Tue, 18 Nov 2008 18:00:00 -0500"
  <br /></span><span style="color: rgb(0, 0, 187);">?&gt;</span></span><br />
</p>

<p>
The Date API provides a helper function, <span style="color: rgb(0, 0, 187);">date_make_date($string, $timezone, $type)</span>,
where $string is a unixtimestamp, an ISO date, or a string like YYYY-MM-DD HH:MM:SS,
$timezone is the name of the timezone this date is in, and $type is the type
of date it is (DATE_UNIX, DATE_ISO, or DATE_DATETIME). It creates and return
a date object set to the right date and timezone.
</p>
